home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / xlib04.zip / XLIBREF1.DOC < prev    next >
Text File  |  1992-11-08  |  59KB  |  1,608 lines
  1. PART 1 of 2
  2. -----------------------------------------------------------------------------
  3.  
  4.   *********      XLIB - Mode X graphics library           ****************
  5.   *********                                               ****************
  6.   ********* Written By Themie Gouthas                     ****************
  7.   *********                                               ****************
  8.   ********* egg@dstos3.dsto.gov.au                        ****************
  9.   ********* teg@bart.dsto.gov.au                          ****************
  10.  
  11.       Some of the code in this library has been contributed by :
  12.  
  13.                Matthew MacKenzie - matm@eng.umd.edu
  14.  
  15.   Notes:
  16.     References to my employer have been removed as this library is my
  17.     own intellectual property, developed solely in my own time.
  18.  
  19.     I informally reserve all rights to the code in XLIB.
  20. -----------------------------------------------------------------------------
  21.  
  22. DISCLAIMER
  23.  
  24.  This library is distributed AS IS. The author/s specifically disclaim
  25.  any responsibility for any loss of profit or any incidental, consequen-
  26.  tial or other damages.
  27.  
  28. ---------------------------------------------------------------------------
  29. INTRODUCTION
  30. ---------------------------------------------------------------------------
  31.  
  32. XLIB is a "user supported freeware" graphics library specifically designed
  33. with game programming in mind.
  34.  
  35. It has been placed in the public domain for the benefit of all, and
  36. represents *MANY* hours of work so it is requested that all users comply
  37. with the the wishes of the author/s as specified in the individual modules
  38. and:
  39. a) To leave the code in the public domain
  40. b) Not distribute any modified or incomplete versions of this library
  41.  
  42. New contribution and comments are welcome and hopefully there will be
  43. more releases as the code evolves.
  44.  
  45. Finally, do not trust this excuse for a manual if in doubt, as this code has
  46. undergone several revisions. The place to get the answers is in the code
  47. itself.
  48.  
  49. REQUIREMENTS
  50.  
  51. Minimum requirements
  52.         286 processor,
  53.     Turbo C 2.0 or higher, or BORLANDC
  54.     MAKE  2.0 or higher
  55.     TLIB  2.0 or higher
  56.     Turbo Assembler 1.01 or higher
  57.  
  58.  
  59. GENERAL FEATURES
  60.  
  61.    Support for a number of 256 colour tweaked graphics mode resolutions
  62.    320x200 320x240 360x200 360x240 376x282 320x400 320x480 360x400 360x480
  63.    360x360 376x308 376x564
  64.  
  65.    Please note that some of the new resolutions best suit monitors with
  66.    adjustable vertical height.
  67.  
  68.    Virtual screens larger than the physical screen (memory
  69.    permitting) that can be panned at pixel resolution in all directions
  70.  
  71.    A split screen capability for status displays etc.
  72.  
  73.    Text functions supporting 8x8 and 8x14 ROM fonts and user defined fonts
  74.  
  75.    Support for page flipping
  76.  
  77.    Graphics primitives such as line and rectangle drawing functions and
  78.    of course bit block manipulation functions
  79.  
  80. MODULES COMPRISING XLIB
  81.    XMAIN    - Main module containig mode setting code and basic functions
  82.    XPOINT   - Pixel functions
  83.    XRECT    - Filled Rectangle and VRAM to VRAM block move functions
  84.    XPAL     - Palette functions
  85.    XLINE    - Line Functions
  86.    XTEXT    - Text and Font Functions
  87.    XPRINTF  - Printf style string output
  88.    XPBITMAP - Planar Bitmap functions
  89.    XCBITMAP - Compiled Bitmap functions
  90.    XVBITMAP - Video Bitmap functions
  91.    XPBMCLIP - Clipped Planar Bitmap functions
  92.    XMAKEVBM - Support module for video bitmaps
  93.    XBMTOOLS - Bitmap format conversion tools
  94.    XDETECT  - Hardware detection module
  95.    XFILEIO  - File I/O functions
  96.    XRLETOOL - RLE encoding/decoding functions
  97.    XMOUSE   - Mouse functions
  98.    XBEZIER  - Bezier curve drawing
  99.  
  100. -------------------------------------------------------------------------
  101. BUILDING THE LIBRARIES
  102. -------------------------------------------------------------------------
  103.  
  104. Building the library had been made simple through the use of make.
  105.  
  106. To build and examples for one of the two models:
  107.  
  108. a) edit the makefile for the apropriate model (see note in the makefile)
  109. b) edit the makefile for the apropriate compiler (again see note in the
  110.    makefile)
  111. c) type "make" at the dos prompt.
  112.  
  113. It should be as simple as that. If problems are encountered then check
  114. to see if tasm, make, tlib, link and bcc (or tcc) are withinin your path.
  115. If not either change your path or specify the full path for these programs
  116. in the makefile. It is preferrable to have your path set correctly.
  117.  
  118. Individual Compilation
  119. ----------------------
  120.  
  121. each ASM module can be compiled with the following commandline:
  122.  
  123. tasm /ml /d<model> <asm module name>
  124.  
  125. where <model> is s c or l. Where s = small model, c = compact model and
  126. l = large model.
  127.  
  128. The resulting libraries are:
  129.  
  130.   xlib<version>s.lib    - small model library
  131.   xlib<version>c.lib    - large model library
  132.   xlib<version>l.lib    - large model library
  133.  
  134. To link the library with your programs just include the apropriate .lib
  135. file in your project file or on the BCC or TCC command line.
  136.  
  137. Using the library with your programs
  138. ------------------------------------
  139.  
  140. Using the XLIB library in your programs is simple. Knowing the particular
  141. modules you require, just include the associated header files in your program
  142. and link your program modules with the library. If you don't want to wory
  143. about selecting the apropriate header file then just include "XLIB_ALL.H"
  144. which automatically includes all XLIB header files in your program.
  145.  
  146. For example compilations see the supplied makefile.
  147.  
  148. --------------------------------------------------------------------------
  149. GLOBAL DEFINES (xlib.inc)
  150. --------------------------------------------------------------------------
  151.  
  152. Types
  153.  
  154.  BYTE unsigned char
  155.  WORD unsigned int
  156.  
  157. Available X mode resolutions
  158.  
  159.  X_MODE_320x200  0
  160.  X_MODE_320x240  1
  161.  X_MODE_360x200  2
  162.  X_MODE_360x240  3
  163.  X_MODE_360x282  4
  164.  X_MODE_320x400  5
  165.  X_MODE_320x480  6
  166.  X_MODE_360x400  7
  167.  X_MODE_360x480  8
  168.  X_MODE_360x360  9
  169.  X_MODE_376x308  10
  170.  X_MODE_376x564  11
  171.  
  172. Palette rotation direction directiion
  173.  
  174.  BACKWARD 0
  175.  FORWARD  1
  176.  
  177.  
  178.  X_MODE_INVALID -1
  179.  ERROR           1
  180.  OK              0
  181.  
  182.  
  183. --------------------------------------------------------------------------
  184. MODULE XMAIN
  185. --------------------------------------------------------------------------
  186.  
  187. The Xmain module is the base module of the XLIB library. It contains the
  188. essential functions that initialize and customize the graphic environment.
  189.  
  190.  
  191. ASM SOURCES
  192.  
  193.    xmain.asm xmain.inc xlib.inc model.inc
  194.  
  195. C HEADER FILE
  196.  
  197.    xlib.h
  198.  
  199. EXPORTED VARIABLES
  200.  
  201.   NOTE: All variables are read only unless otherwise specified. If you modify
  202.   them manually, the results may be unpredictable.
  203.  
  204.   InGraphics -  BYTE -  Flag indicating that the xlib graphics system is
  205.        active. Set by function "x_set_mode".
  206.  
  207.   CurrXMode - WORD - If the xlib graphics system is active, contains the id
  208.        of the x mode. Set by function "x_set_mode".
  209.        See also defines (ie X_MODE_320x200 ... )
  210.  
  211.   ScrnPhysicalByteWidth - WORD - Physical screen width in bytes. Set by
  212.        function "x_set_mode"
  213.  
  214.   ScrnPhysicalPixelWidth - WORD - Physical screen width in pixels. Set by
  215.        function "x_set_mode"
  216.  
  217.   ScrnPhysicalHeight - WORD - Physical screen height in pixels. Set by
  218.        function "x_set_mode".
  219.  
  220.   ErrorValue - WORD - Contains error value. General use variable to
  221.        communicate the error status from several functions. The value
  222.        in this variable usually is only valid for the the last
  223.        function called that sets it.
  224.  
  225.   SplitScrnOffs - WORD - Offset in video ram of split screen. Set by
  226.        function "x_set_splitscrn". The value is only valid if a split
  227.        screen is active. See also global variable "SplitScrnActive".
  228.  
  229.   SplitScrnScanLine - WORD - Screen Scan Line the Split Screen starts at
  230.        initially when set by function "x_set_splitscrn". The value is only
  231.        valid if a split screen is active. See also global variable
  232.        "SplitScrnActive".This variable is not updated by "x_hide_splitscrn",
  233.        "x_adjust_splitscrn".
  234.  
  235.   SplitScrnVisibleHeight - WORD - The number of rows of the initial split
  236.        screen which are currently displayed. Modified by "x_hide_splitscrn",
  237.        "x_adjust_splitscrn" and "x_show_splitscrn".
  238.  
  239.   Page0_Offs - WORD - Offset in video ram of main virtual screen. Initially
  240.        set by function "x_set_mode" but is updated by functions
  241.        "x_set_splitscrn" and "x_set_doublebuffer".
  242.  
  243.   Page1_Offs - WORD - Offset in video ram of second virtual screen. Set by
  244.        and only is valid after a call to "x_set_doublebuffer".
  245.  
  246.   ScrnLogicalByteWidth - WORD - Virtual screen width in bytes. Set by
  247.        function "x_set_mode".
  248.  
  249.   ScrnLogicalPixelWidth - WORD - Virtual screen width in pixels. Set
  250.        by function "x_set_mode".
  251.  
  252.   ScrnLogicalHeight - WORD - Virtual screen height in pixels. Set
  253.        initially by function "x_set_mode" but is updated by functions
  254.        "x_set_splitscrn" and "x_set_doublebuffer".
  255.  
  256.   MaxScrollX - WORD - Max X pixel position of physical screen within
  257.        virtual screen. Set by function "x_set_mode".
  258.  
  259.   MaxScrollY - WORD - Max Y position of physical screen within virtual
  260.        screen. Set initially by function "x_set_mode" but is updated by
  261.        functions "x_set_splitscrn" and "x_set_doublebuffer".
  262.  
  263.   DoubleBufferActive - WORD - Indicates whether double-buffering is on. Set
  264.        by function "x_set_doublebuffer".
  265.  
  266.   VisiblePageIdx - WORD - Index number of current visible page. Initially
  267.        set by function "x_set_doublebuffer" but is updated by "x_page_flip".
  268.        This variable is only used while double buffering is on.
  269.  
  270.   HiddenPageOffs - WORD - Offset of hidden page. Initially set by function
  271.        "x_set_doublebuffer" but is updated by "x_page_flip". This variable
  272.        is only used while double buffering is on.
  273.  
  274.   VisiblePageOffs - WORD - Offset of visible page. Initially set by function
  275.        "x_set_doublebuffer" but is updated by "x_page_flip". This variable
  276.        is only used while double buffering is on.
  277.  
  278.   NonVisual_Offs - WORD - Offset of first byte of non-visual ram, the ram
  279.        that is available for bitmap storage etc. Set initially by function
  280.        "x_set_mode" but is updated by functions "x_set_splitscrn" and
  281.        "x_set_doublebuffer".
  282.  
  283.   TopClip, BottomClip, LeftClip RightClip - WORD - Define the clipping
  284.        rectangle for Linear and Video clipped bitmap put functions. Set
  285.        either manually or by "x_set_cliprect". Note X coordinates are in
  286.        bytes as all clip functions clip to byte boundaries.
  287.  
  288.   PhysicalStartPixelX - WORD - X pixel Offset of physical (visible) screen
  289.        relative to the upper left hand corner (0,0) of the virtual screen.
  290.  
  291.   PhysicalStartByteX - WORD - X byte Offset of physical (visible) screen
  292.        relative to the upper left hand corner (0,0) of the virtual screen.
  293.  
  294.   PhysicalStartY - WORD - Y pixel Offset of physical (visible) screen
  295.        relative to the upper left hand corner (0,0) of the virtual screen.
  296.  
  297. EXPORTED FUNCTIONS
  298.  
  299.   x_set_mode
  300.   ----------
  301.     C Prototype:  extern WORD x_set_mode(WORD mode,WORD WidthInPixels);
  302.  
  303.      mode          - The required mode as defined by the "Available X Mode
  304.                      resolutions" set of defines in the xlib.h header file.
  305.      WidthInPixels - The required virtual screen width.
  306.      Returns       - The actual width in pixels of the allocated virtual
  307.                      screen
  308.  
  309.   This function initialises the graphics system, setting the apropriate
  310.   screen resolution and allocating a virtual screen. The virtual screen
  311.   allocated may not necessarily be of the same size as specified in the
  312.   "WidthInPixels" parameter as it is rounded down to the nearest
  313.   multiple of 4.
  314.  
  315.   The function returns the actual width of the allocated virtual screen
  316.   in pixels if a valid mode was selected otherwise returns
  317.   X_MODE_INVALID.
  318.  
  319.   Saves virtual screen pixel width in "ScrnLogicalPixelWidth".
  320.   Saves virtual screen byte  width in "ScrnLogicalByteWidth".
  321.   Physical screen dimensions are set in "ScrnPhysicalPixelWidth".
  322.   "ScrnPhysicalByteWidth" and "ScrnPhysicalHeight". Other global
  323.   variables set are "CurrXMode","MaxScrollX", "MaxScrollY",
  324.   "InGraphics". The variable "SplitScrnScanline" is also initialized
  325.   to zero.
  326.  
  327.   See also:
  328.      Available X Mode resolutions
  329.      What is Mode X
  330.  
  331.   x_select_default_plane
  332.   ----------------------
  333.  
  334.     C Prototype:  void x_select_default_plane(BYTE plane);
  335.  
  336.     Enables default Read/Write access to a specified plane
  337.  
  338.  
  339.   x_set_splitscreen
  340.   -----------------
  341.  
  342.     C Prototype:  extern void x_set_splitscreen(WORD line);
  343.  
  344.     line - The starting scan line of the required split screen.
  345.  
  346.   This function activates Mode X split screen and sets starting scan
  347.   line. The split screen resides on the bottom half of the screen and has
  348.   a starting address of A000:0000 in video RAM.
  349.  
  350.   It also Updates Page0_Offs to reflect the existence of the split screen
  351.   region ie "MainScrnOffset" is set to the offset of the first pixel
  352.   beyond the split screen region. Other variable set are "Page1_Offs" which
  353.   is set to the same value as "Page0_Offs" (see graphics call sequence
  354.   below), "ScrnLogicalHeight","ScrnPhysicalHeight", "SplitScrnScanLine" and
  355.   "MaxScrollY".
  356.  
  357.   This function cannot be called after double buffering has been activated,
  358.   it will return an error. To configure your graphics environment the
  359.   sequence of graphics calls is as follows although either or both steps b
  360.   and c may be omitted:
  361.     a) x_set_mode
  362.     b) x_set_splitscreen
  363.     c) x_set_doublebuffer
  364.   Thus when you call this function successfully, double buffering is not
  365.   active so "Page1_Offs" is set to the same address as "Page0_Offs".
  366.  
  367.   WARNING: If you use one of the high resolution modes (376x564 as an
  368.     extreme example) you may not have enough video ram for split screen
  369.     and double buffering options since VGA video RAM is restricted to
  370.     64K.
  371.  
  372.   See Also:
  373.     What is a Split Screen ?
  374.     What is double buffering ?
  375.  
  376.   x_set_doublebuffer
  377.   ------------------
  378.  
  379.   C Prototype: extern WORD x_set_doublebuffer(WORD PageHeight);
  380.  
  381.   PageHeight - The height of the two double buffering virtual screens.
  382.   Returns    - The closest possible height to the specified.
  383.  
  384.   This function sets up two double buffering virtual pages. 'ErrorValue"
  385.   is set according to the success or failure of this command.
  386.  
  387.   Other variables set are:
  388.  
  389.     _Page1_Offs                 Offset of second virtual page
  390.     _NonVisual_Offs          Offset of first non visible video ram byte
  391.     _DoubleBufferActive      Flag
  392.     _PageAddrTable           Table of Double buffering pages start offsets
  393.     _ScrnLogicalHeight       Logical height of the double buffering pages
  394.     _MaxScrollY              Max vertical start address of physical screen
  395.                              within the virtual screen
  396.  
  397.   WARNING: If you use one of the high resolution modes (376x564 as an
  398.     extreme example) you may not have enough video ram for split screen
  399.     and double buffering options since VGA video RAM is restricted to
  400.     64K.
  401.  
  402.   See Also:
  403.     What is double buffering ?
  404.  
  405.   x_hide_splitscreen
  406.   ------------------
  407.  
  408.   C Prototype: extern void x_hide_splitscreen(void);
  409.  
  410.  
  411.   This function hides an existing split screen by setting its starting
  412.   scan line to the last physical screen scan line.
  413.   "ScreenPhysicalHeight" is adjusted but the "SplitScreenScanLine" is not
  414.   altered as it is required for restoring the split screen at a later stage.
  415.  
  416.   WARNING: Only to be used if SplitScrnLine has been previously called
  417.        Disabled for mode 5-11 (320x400-376x564). The memory for
  418.         the initial split screen is reserved and the size limitations
  419.        of these modes means any change in the split screen scan line
  420.            will encroach on the split screen ram
  421.            Update: Now disabled for these modes
  422.  
  423.   See Also:
  424.  
  425.     What is a split screen ?
  426.  
  427.   x_show_splitscreen
  428.   ------------------
  429.  
  430.   C Prototype: extern void x_show_splitscreen(void);
  431.  
  432.   Restores split screen start scan line to the initial split screen
  433.   starting scan line as set by "SplitScrnScanLine".
  434.   "ScreenPhysicalHeight" is adjusted.
  435.  
  436.   WARNING: Only to be used if SplitScrnLine has been previously called
  437.        Disabled for mode 4-10 (320x400-376x564). The memory for
  438.         the initial split screen is reserved and the size limitations
  439.         of these modes means any change in the split screen scan line
  440.            will encroach on the split screen ram
  441.  
  442.  
  443.   x_adjust_splitscreen
  444.   --------------------
  445.  
  446.   C Prototype: extern void x_adjust_splitscreen(WORD line);
  447.  
  448.   line - The scan line at which the split screen is to start.
  449.  
  450.   Sets the split screen start scan line to a new scan line. Valid scan lines
  451.   are between the initial split screen starting scan line and the last
  452.   physical screen scan line. "ScreenPhysicalHeight" is also adjusted.
  453.  
  454.   WARNING: Only to be used if SplitScrnLine has been previously called
  455.        Disabled for mode 4-10 (320x400-376x564). The memory for
  456.         the initial split screen is reserved and the size limitations
  457.         of these modes means any change in the split screen scan line
  458.            will encroach on the split screen ram
  459.  
  460.   x_set_start_addr
  461.   ----------------
  462.  
  463.   C Prototype: extern void x_set_start_addr(WORD X,WORD Y);
  464.  
  465.     X,Y - coordinates of top left corner of physical screen within current
  466.       virtual screen.
  467.  
  468.   Set Mode X non split screen physical start address within current virtual
  469.   page.
  470.  
  471.   X must not exceed (Logical screen width - Physical screen width)
  472.   ie "MaxScrollX" and Y must not exceed (Logical screen height -
  473.   Physical screen height) ie "MaxScrollY"
  474.  
  475.   x_page_flip
  476.   -----------
  477.  
  478.   C Prototype: extern void x_page_flip(WORD X,WORD Y);
  479.  
  480.     X,Y - coordinates of top left corner of physical screen within the
  481.       the hidden virtual screen if double buffering is active, or
  482.       the current virtual screen otherwise.
  483.  
  484.   Sets the physical screen start address within currently hidden virtual
  485.   page and then flips pages. If double buffering is not active then this
  486.   function is functionally equivalent to "x_set_start_addr".
  487.  
  488.   X must not exceed (Logical screen width - Physical screen width)
  489.   ie "MaxScrollX" and Y must not exceed (Logical screen height -
  490.   Physical screen height) ie "MaxScrollY"
  491.  
  492.   x_text_mode
  493.   -----------
  494.  
  495.   C Prototype: extern void x_text_mode(void);
  496.  
  497.   Disables graphics mode.
  498.  
  499.   x_set_cliprect
  500.   --------------
  501.  
  502.   C Prototype: extern void x_set_cliprect(WORD left,WORD top,WORD right,
  503.         WORD bottom);
  504.  
  505.   Defines the clipping rectangle for clipping versions of planar and video
  506.   bitmap puts.
  507.  
  508.   NOTE: Compiled bitmaps cannot be clipped.
  509.  
  510.  
  511. --------------------------------------------------------------------------
  512. MODULE XPOINT
  513. --------------------------------------------------------------------------
  514.  
  515.   Point functions all MODE X 256 Color resolutions
  516.  
  517.   ASM SOURCES
  518.  
  519.     xpoint.asm xpoint.inc xlib.inc model.inc
  520.  
  521.   C HEADER FILE
  522.  
  523.    xpoint.h
  524.  
  525.   EXPORTED FUNCTIONS
  526.  
  527.   x_put_pix
  528.   ---------
  529.  
  530.   C Prototype: extern void x_put_pix(WORD X,WORD Y,WORD PageOffset,
  531.                                      WORD Color);
  532.  
  533.   Draw a point of specified colour at coordinates X,Y
  534.   within the virtual page starting at offset PageOffset.
  535.  
  536.   x_get_pix
  537.   ---------
  538.  
  539.   C Prototype: extern WORD x_get_pix(WORD X, WORD Y, WORD PageBase);
  540.  
  541.   Read a point of at coordinates X,Y within the virtual page starting
  542.   at offset PageOffset.
  543.  
  544.  
  545. --------------------------------------------------------------------------
  546. MODULE XRECT
  547. --------------------------------------------------------------------------
  548.  
  549.   Screen rectangle display and manipulation functions
  550.  
  551.   ASM SOURCES
  552.  
  553.     xrect.asm xrect.inc xlib.inc model.inc
  554.  
  555.   C HEADER FILE
  556.  
  557.     xrect.h
  558.  
  559.  
  560.   EXPORTED FUNCTIONS
  561.  
  562.   x_rect_pattern
  563.   --------------
  564.  
  565.   C Prototype: extern void x_rect_pattern(WORD StartX, WORD StartY,
  566.                                           WORD EndX, WORD EndY,
  567.                                           WORD PageBase,BYTE far *Pattern);
  568.  
  569.   StartX,StartY - Coordinates of upper left hand corner of rectangle
  570.   EndX,EndY     - Coordinates of lower right hand corner of rectangle
  571.   PageBase      - Offset of virtual screen
  572.   *Pattern      - Pointer to the user defined pattern (16 bytes)
  573.  
  574.  
  575.   Mode X rectangle 4x4 pattern fill routine.
  576.  
  577.   Upper left corner of pattern is always aligned to a multiple-of-4
  578.   row and column. Works on all VGAs. Uses approach of copying the
  579.   pattern to off-screen display memory, then loading the latches with
  580.   the pattern for each scan line and filling each scan line four
  581.   pixels at a time. Fills up to but not including the column at EndX
  582.   and the row at EndY. No clipping is performed.
  583.  
  584.   Based on code originally published in DDJ Mag by M. Abrash
  585.  
  586.   Warning the VGA memory locations PATTERN_BUFFER (A000:FFFc) to
  587.   A000:FFFF are reserved for the pattern buffer
  588.  
  589.  
  590.   See Also:
  591.     Doctor Dobbs Journal references.
  592.  
  593.   x_rect_fill
  594.   -----------
  595.  
  596.   C Prototype: extern void x_rect_fill(WORD StartX,WORD StartY,
  597.                                        WORD EndX,WORD EndY,
  598.                                        WORD PageBase,WORD color);
  599.  
  600.   StartX,StartY - Coordinates of upper left hand corner of rectangle
  601.   EndX,EndY - Coordinates of lower right hand corner of rectangle
  602.   PageBase - Offset of virtual screen
  603.   Color -color to use for fill
  604.  
  605.   Mode X rectangle solid color fill routine.
  606.   Based on code originally published in DDJ Mag by M. Abrash
  607.  
  608.   See Also:
  609.     Doctor Dobbs Journal references.
  610.  
  611.   x_cp_vid_rect
  612.   -------------
  613.  
  614.   C Prototype: extern void x_cp_vid_rect(WORD SourceStartX,WORD SourceStartY,
  615.                           WORD SourceEndX,WORD SourceEndY,
  616.                           WORD DestStartX,WORD DestStartY,
  617.                           WORD SourcePageBase,WORD DestPageBase,
  618.                           WORD SourceBitmapWidth,WORD DestBitmapWidth);
  619.  
  620.   StartX,StartY- Coordinates of upper left hand corner of source rectangle
  621.   EndX,EndY    - Coordinates of lower right hand corner of source rectangle
  622.   DestStartX,DestStartY - Coordinates of rectangle destination
  623.   SourcePageBase        - source rectangle page offset
  624.   DestPageBase          - destination rectangles page offset
  625.   SourceBitmapWidth     - width of bitmap within the source virtual screen
  626.                           containing the source rectangle
  627.   DestBitmapWidth       - width of bitmap within the dest. virtual screen
  628.                           containing the destination rectangle
  629.  
  630.   Mode X display memory to display memory copy
  631.   routine. Left edge of source rectangle modulo 4 must equal left edge
  632.   of destination rectangle modulo 4. Works on all VGAs. Uses approach
  633.   of reading 4 pixels at a time from the source into the latches, then
  634.   writing the latches to the destination. Copies up to but not
  635.   including the column at SrcEndX and the row at SrcEndY. No
  636.   clipping is performed. Results are not guaranteed if the source and
  637.   destination overlap.
  638.  
  639.  
  640.   Based on code originally published in DDJ Mag by M. Abrash
  641.  
  642.   See Also:
  643.     Doctor Dobbs Journal references.
  644.  
  645.   x_shift_rect
  646.   ------------
  647.  
  648.   C Prototype:
  649.   extern void x_shift_rect (WORD SrcLeft, WORD SrcTop,
  650.             WORD SrcRight, WORD SrcBottom,
  651.             WORD DestLeft, WORD DestTop, WORD ScreenOffs);
  652.  
  653.   SrcLeft, SrcTop - Coordinates of upper left hand corner of rectangle
  654.   SrcRight, SrcBottom - Coordinates of lower right hand corner of rectangle
  655.   DestLeft, DestTop - Coordinates of upper left corner of destination
  656.   ScreenOffs    - Offset of virtual screen
  657.  
  658.   This function copies a rectangle of VRAM onto another area of VRAM,
  659.   even if the destination overlaps with the source.  It is designed
  660.   for scrolling text up and down, and for moving large areas of screens
  661.   around in tiling systems.  It rounds all horizontal coordinates to
  662.   the nearest byte (4-column chunk) for the sake of speed.  This means
  663.   that it can NOT perform smooth horizontal scrolling.  For that,
  664.   either scroll the whole screen (minus the split screen), or copy
  665.   smaller areas through system memory using the functions in the
  666.   XPBITMAP module.
  667.  
  668.   SrcRight is rounded up, and the left edges are rounded down, to
  669.   ensure that the pixels pointed to by the arguments are inside the
  670.   the rectangle.  That is, SrcRight is treated as (SrcRight+3) >> 2,
  671.   and SrcLeft as SrcLeft >> 2.
  672.  
  673.   The width of the rectangle in bytes (width in pixels / 4)
  674.   cannot exceed 255.
  675.  
  676. ---------------------------------------------------------------------------
  677. MODULE XPAL
  678. ---------------------------------------------------------------------------
  679.  
  680.     Palette functions for VGA 256 color modes.
  681.  
  682.     All the functions in this module operate on two variations of the
  683.     pallete buffer, the raw and annotated buffers.
  684.  
  685.     All those functions ending in "raw" operate on the following palette
  686.     structure:
  687.  
  688.        BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn
  689.  
  690.     No reference to the starting colour index or number of colours stored
  691.     is contained in the structure.
  692.  
  693.     All those functions ending in "struc" operate on the following palette
  694.     structure:
  695.  
  696.        BYTE:c,BYTE:n,BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn
  697.  
  698.     where c is the starting colour and n is the number of colours stored
  699.  
  700.  
  701.     WARNING: There is no validity checking in these functions. The onus is
  702.     on the user to supply valid parameters to the functions.
  703.  
  704.  
  705.   ASM SOURCES
  706.  
  707.     xpal.asm xpal.inc xlib.inc model.inc
  708.  
  709.   C HEADER FILE:
  710.  
  711.     xpal.h
  712.  
  713.   EXPORTED FUNCTIONS
  714.  
  715.   x_get_pal_raw
  716.   -------------
  717.  
  718.   C Prototype: extern void x_get_pal_raw(BYTE far * pal,WORD num_colrs,
  719.                                          WORD start_index);
  720.  
  721.   Read DAC palette into raw buffer with interrupts disabled
  722.   ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn
  723.  
  724.   WARNING: Memory for the palette buffers must all be pre-allocated.
  725.  
  726.   x_get_pal_struc
  727.   ---------------
  728.  
  729.   C Prototype: extern void x_get_pal_struc(BYTE far * pal,WORD num_colrs,
  730.                                               WORD start_index);
  731.  
  732.   Read DAC palette into annotated type buffer with interrupts disabled
  733.   ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn
  734.  
  735.   WARNING: memory for the palette buffers must all be pre-allocated
  736.  
  737.   x_put_pal_raw
  738.   -------------
  739.  
  740.   C Prototype: extern void x_put_pal_raw(BYTE far * pal,WORD num_colrs,
  741.                                          WORD start_index);
  742.  
  743.   Write DAC palette from raw buffer with interrupts disabled
  744.   ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn
  745.  
  746.   x_put_pal_struc
  747.   --------------
  748.  
  749.   C Prototype: extern void x_put_pal_struc(BYTE far * pal);
  750.  
  751.   Write DAC palette from annotated type buffer with interrupts disabled
  752.   ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn
  753.  
  754.   x_set_rgb
  755.   ---------
  756.  
  757.   C Prototype: extern x_set_rgb(BYTE color,BYTE red_c,BYTE green_c,
  758.                                BYTE blue_c);
  759.  
  760.   Set the RGB components of a vga color
  761.  
  762.   x_rot_pal_struc
  763.   ---------------
  764.  
  765.   C Prototype: extern void x_rot_pal_struc(BYTE far * pal,WORD direction);
  766.  
  767.   Rotate annotated palette buffer entries. Direction 0 = backward,
  768.   1 = forward.
  769.  
  770.   x_rot_pal_raw
  771.   -------------
  772.  
  773.   C Prototype: extern x_rot_pal_raw(BYTE far * pal,WORD direction,
  774.                                     WORD num_colrs);
  775.  
  776.   Rotate a raw palette buffer. Direction 0 = backward,
  777.   1 = forward.
  778.  
  779.   x_put_contrast_pal_struc
  780.   ------------------------
  781.  
  782.   C Prototype: extern  void x_put_contrast_pal_struc(BYTE far * pal,
  783.                BYTE  intensity);
  784.  
  785.   Write DAC palette from annotated type buffer with specified intensity
  786.   adjustment (ie palette entries are decremented where possible by
  787.   "intensity" units).
  788.  
  789.   Designed for fading in or out a palette without using an intermediate
  790.   working palette buffer ! (Slow but memory efficient ... OK for small
  791.   pal strucs}
  792.  
  793.  
  794.   x_transpose_pal_struc
  795.   ---------------------
  796.  
  797.   C Prototype: extern void x_transpose_pal_struc(BYTE far * pal,
  798.                                                  WORD StartColor);
  799.  
  800.   Write DAC palette from annotated type buffer with interrupts disabled
  801.   starting at a new palette index.
  802.  
  803.  
  804.   x_cpcontrast_pal_struc
  805.   ----------------------
  806.  
  807.   C Prototype: extern WORD x_cpcontrast_pal_struc(BYTE far *src_pal,
  808.                                 BYTE far *dest_pal,BYTE Intensity);
  809.  
  810.   Copy one annotated palette buffer to another making the intensity
  811.   adjustment. Used in fading in and out fast and smoothly.
  812.  
  813. ---------------------------------------------------------------------------
  814. MODULE XLINE
  815. ---------------------------------------------------------------------------
  816.  
  817.   Line Drawing functions.
  818.  
  819.   ASM SOURCES
  820.  
  821.     xline.asm xline.inc xlib.inc model.inc
  822.  
  823.   C HEADER FILE
  824.  
  825.     xline.h
  826.  
  827.   EXPORTED FUNCTIONS
  828.  
  829.   x_line
  830.   ------
  831.  
  832.   C Prototype: extern void x_line(WORD x0,WORD y0,WORD x1,WORD y1,
  833.                                   WORD color,WORD PageBase);
  834.  
  835.   Draw a line with the specified end points in the page starting at
  836.   offset "PageBase".
  837.  
  838.   No Clipping is performed.
  839.  
  840. ---------------------------------------------------------------------------
  841. MODULE XTEXT
  842. ---------------------------------------------------------------------------
  843.  
  844.   ASM SOURCES
  845.  
  846.     xtext.asm xtext.inc xlib.inc model.inc
  847.  
  848.   C HEADER FILE
  849.  
  850.     xtext.h
  851.  
  852.   MACROS
  853.  
  854.    FONT_8x8  0
  855.    FONT_8x15 1
  856.    FONT_USER 2
  857.  
  858.   EXPORTED VARIABLES
  859.  
  860.     NOTE: All variables are read only. I you modify them the results may
  861.     be unpredictable.
  862.  
  863.     CharHeight - BYTE - Height of current inbuilt character set
  864.  
  865.     CharWidth  - BYTE - Width of current inbuilt character set
  866.  
  867.     FirstChar  - BYTE - First character of current inbuilt character set
  868.  
  869.     UserCharHeight - BYTE - Height of current user character set
  870.  
  871.     UserCharWidth - BYTE - Width of current user character set
  872.  
  873.     UserFirstCh - BYTE - First character of current user character set
  874.  
  875.  
  876.   EXPORTED FUNCTIONS
  877.  
  878.   x_text_init
  879.   -----------
  880.  
  881.   C Prototype: extern WORD x_text_init(void);
  882.  
  883.   Initializes the Mode X text driver and sets the default font (VGA ROM 8x8)
  884.  
  885.   x_set_font
  886.   ----------
  887.  
  888.   C Prototype: extern void x_set_font(WORD FontId);
  889.  
  890.   Select the working font where 0 = VGA ROM 8x8, 1 = VGA ROM 8x14
  891.   2 = User defined bitmapped font.
  892.  
  893.   WARNING: A user font must be registered before setting FontID 2
  894.  
  895.   See Also:
  896.  
  897.     Defines for this module
  898.  
  899.   x_register_userfont
  900.   -------------------
  901.  
  902.   C Prototype: extern void x_register_userfont(char far *UserFontPtr);
  903.  
  904.  
  905.   Register a user font for later selection. Only one user font can be
  906.   registered at any given time. Registering a user font deregisters the
  907.   previous user font. User fonts may be at most 8 pixels wide.
  908.  
  909.   USER FONT STRUCTURE
  910.  
  911.   Word:  ascii code of first char in font
  912.   Byte:  Height of chars in font
  913.   Byte:  Width of chars in font
  914.   n*h*Byte: the font data where n = number of chars and h = height
  915.       of chars
  916.  
  917.   WARNING: The onus is on the program to ensure that all characters
  918.            drawn whilst this font is active, are within the range of
  919.            characters defined.
  920.  
  921.   x_put_char
  922.   ----------
  923.  
  924.   C Prototype: extern void x_put_char(char ch,WORD X,WORD Y,WORD PgOffs,
  925.                                       WORD Color);
  926.  
  927.   Draw a text character at the specified location with the specified
  928.   color.
  929.  
  930.   ch       -  char to draw
  931.   x,y      -  screen coords at which to draw ch
  932.   ScrnOffs -  Starting offset of page on whih to draw
  933.   Color    -  Color of the text
  934.  
  935.   WARNING: InitTextDriver must be called before using this function
  936.  
  937.  
  938.   **** NOTE ****
  939.  
  940.   The file "xprintf.c" implements a printf style formatted output function
  941.  
  942.   x_printf
  943.   --------
  944.  
  945.   C Prototype: void x_printf(int x,int y,unsigned ScrnOffs,int color,
  946.                char *ln,...);
  947.  
  948.   x,y      -  screen coords at which to draw ch
  949.   ScrnOffs -  Starting offset of page on whih to draw
  950.   Color    -  Color of the text
  951.  
  952.   Parameters beyond Color conform to the standard printf parameters.
  953.  
  954.   x_bgprintf
  955.   ----------
  956.  
  957.   C Prototype: void x_bgprintf(int x,int y,unsigned ScrnOffs,int fgcolor,
  958.            int bgcolor, char *ln,...);
  959.  
  960.   x,y      -  screen coords at which to draw ch
  961.   ScrnOffs -  Starting offset of page on whih to draw
  962.   fgcolor    -  Color of the text foreground
  963.   bgcolor    -  Color of the text background
  964.  
  965.   Parameters beyond bgolor conform to the standard printf parameters.
  966.  
  967.  
  968. --------------------------------------------------------------------------
  969. MODULE XPBITMAP
  970. --------------------------------------------------------------------------
  971.  
  972.   This module implements a set of functions to operate on planar bitmaps.
  973.   Planar bitmaps as used by these functions have the following structure:
  974.  
  975.   BYTE 0                 The bitmap width in bytes (4 pixel groups) range 1..255
  976.   BYTE 1                 The bitmap height in rows range 1..255
  977.   BYTE 2..n1             The plane 0 pixels width*height bytes
  978.   BYTE n1..n2            The plane 1 pixels width*height bytes
  979.   BYTE n2..n3            The plane 2 pixels width*height bytes
  980.   BYTE n3..n4            The plane 3 pixels width*height bytes
  981.  
  982.   These functions provide the fastest possible bitmap blts from system ram to
  983.   to video and further, the single bitmap is applicable to all pixel
  984.   allignments. The masked functions do not need separate masks since all non
  985.   zero pixels are considered to be masking pixels, hence if a pixel is 0 the
  986.   corresponding screen destination pixel is left unchanged.
  987.  
  988.  
  989.   ASM SOURCES
  990.  
  991.     xpbitmap.asm xpbitmap.inc xlib.inc model.inc
  992.  
  993.   C HEADER FILE
  994.  
  995.     xpbitmap.h
  996.  
  997.   EXPORT FUNCTIONS
  998.  
  999.   x_put_masked_pbm
  1000.   ----------------
  1001.  
  1002.   C Prototype: extern void x_put_masked_pbm(WORD X,WORD Y,WORD ScrnOffs,
  1003.                  BYTE far * Bitmap);
  1004.  
  1005.   Mask write a planar bitmap from system ram to video ram. All zero source
  1006.   bitmap bytes indicate destination byte to be left unchanged.
  1007.  
  1008.   Source Bitmap structure:
  1009.  
  1010.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  1011.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  1012.  
  1013.   NOTE: width is in bytes ie lots of 4 pixels
  1014.  
  1015.   LIMITATIONS: No clipping is supported
  1016.                Only supports bitmaps with widths which are a multiple of
  1017.                4 pixels
  1018.  
  1019.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  1020.      functions.
  1021.  
  1022.   x_put_pbm
  1023.   ---------
  1024.  
  1025.   C Prototype: extern void x_put_pbm(WORD X, WORD Y, WORD ScrnOffs,
  1026.                  BYTE far * Bitmap);
  1027.  
  1028.   Write a planar bitmap from system ram to video ram.
  1029.  
  1030.   Source Bitmap structure:
  1031.  
  1032.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  1033.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  1034.  
  1035.   NOTE: width is in bytes ie lots of 4 pixels
  1036.  
  1037.   LIMITATIONS: No clipping is supported
  1038.                Only supports bitmaps with widths which are a multiple of
  1039.                4 pixels
  1040.  
  1041.  
  1042.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  1043.      functions.
  1044.  
  1045.   x_get_pbm
  1046.   ---------
  1047.  
  1048.   C Prototype: extern void x_get_pbm(WORD X, WORD Y,BYTE Bw,BYTE Bh,
  1049.                WORD ScrnOffs, BYTE far * Bitmap);
  1050.  
  1051.   Read a planar bitmap to system ram from video ram.
  1052.  
  1053.   Source Bitmap structure:
  1054.  
  1055.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  1056.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  1057.  
  1058.   NOTE: width is in bytes ie lots of 4 pixels
  1059.  
  1060.   LIMITATIONS: No clipping is supported
  1061.                Only supports bitmaps with widths which are a multiple of
  1062.                4 pixels
  1063.  
  1064.  
  1065.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  1066.      functions.
  1067.  
  1068. --------------------------------------------------------------------------
  1069. MODULE XPBMCLIP
  1070. --------------------------------------------------------------------------
  1071.  
  1072.   This module implements a similar set of functions to operate on planar
  1073.   bitmaps as "XPBITMAP" but incorporates clipping to a user defined
  1074.   clipping rectangle (which is set by "x_set_cliprect" in module xmain).
  1075.  
  1076.   The planar bitmap format is identical to the above module
  1077.  
  1078.   There are three variations of the functions in XPBITMAP in this module
  1079.   identified by the three function name extensions: _clipx, _clipy _clipxy.
  1080.   Because speed is critical in games programming you do not want to be
  1081.   checking for clipping if not necessary thus for sprites that move only
  1082.   horizontally you would use the _clipx version of the put function,
  1083.   for sprites that move vertically you would use the _clipy version and for
  1084.   sprites that move both directions you would use the clipxy version.
  1085.   Keep in mind also that the clipping components of these functions assume
  1086.   that the clipping rectangle is equal to or larger than the size of the
  1087.   bitmap ie. if a bitmap is top clipped, it is assumed that the bitmap's
  1088.   bottom is not also clipped. Similarly with horizontal clipping.
  1089.  
  1090.   Note: performance in decreasing order is as follows.
  1091.     _clipy,_clipx,_clipxy with masked puts being slower than unmasked
  1092.     puts
  1093.  
  1094.   Horizontal clipping is performed to byte boundaries (4 pixels) rather than
  1095.   pixels. This allows for the fastest implementation of the functions. It is
  1096.   not such a handicap because for one, your screen width a multiple of 4
  1097.   pixels wide and  for most purposes it is the screen edges that form the
  1098.   clipping rectangle.
  1099.  
  1100.   Following is an example of setting a clipping rectangle to the logical
  1101.   screen edges:
  1102.  
  1103.   x_set_cliprect(0,0,ScrnLogicalByteWidth,ScrnLogicalHeight)
  1104.  
  1105.  
  1106.  
  1107.   ASM SOURCES
  1108.  
  1109.     xpbmclip.asm xpbmclip.inc xlib.inc model.inc
  1110.  
  1111.   C HEADER FILE
  1112.  
  1113.     xpbmclip.h
  1114.  
  1115.   EXPORT FUNCTIONS
  1116.  
  1117.   x_put_pbm_clipx
  1118.   ---------------
  1119.   x_put_pbm_clipy
  1120.   ---------------
  1121.   x_put_pbm_clipxy
  1122.   ----------------
  1123.   x_put_masked_pbm_clipx
  1124.   ----------------------
  1125.   x_put_masked_pbm_clipy
  1126.   ----------------------
  1127.   x_put_masked_pbm_clipxy
  1128.   -----------------------
  1129.  
  1130.   For a detailed description of parameters etc. see equivalent functions
  1131.   in module "XPBITMAP".
  1132.  
  1133.  
  1134. --------------------------------------------------------------------------
  1135. MODULE  XCBITMAP
  1136. --------------------------------------------------------------------------
  1137.  
  1138.                                  XCBITMAP:
  1139.                The Care and Feeding of Compiled Masked Blits
  1140.                            by Matthew MacKenzie
  1141.  
  1142. The XCBITMAP module of the Xlib library is made up of the files
  1143. XCBITMAP.ASM, XCBITMAP.INC, and XCBITMAP.H.
  1144.  
  1145. The XCBITMAP module is small, containing only three procedures:
  1146.   o  x_compile_bitmap compiles your bitmap into native code which writes
  1147.      to the VGA screen in an X mode.
  1148.   o  x_put_cbitmap converts X and Y coordinates into a location on the
  1149.      screen, sets up the necessary VGA registers, and executes the compiled
  1150.      bitmap as a subroutine.
  1151.   o  x_sizeof_cbitmap takes a planar bitmap and returns an integer equal to
  1152.      the size of the compiled bitmap which the planar bitmap would produce.
  1153.      It is essentially a lobotomized version of x_compile_bitmap, with all
  1154.      the code generation replaced with a size counter.
  1155.  
  1156.     x_compile_bitmap scans through a source bitmap and generates 8086
  1157. instructions to plot every nonzero pixel.  It is designed to be used
  1158. before the action begins rather than on-the-fly.  The compiled bitmap
  1159. contains no branches, and no reference to the zero (transparent) pixels.
  1160. Where two pixels are exactly four columns apart they are plotted with a
  1161. single 16-bit store, and the VGA MAP_MASK register will be set at most
  1162. four times.  As a result your bitmap may run several times faster than a
  1163. traditional memory-to-VGA masked blit routine.
  1164.     There is no way to perform clipping on these bitmaps, or to plot a
  1165. pixel of color zero.
  1166.     x_compile_bitmap works with bitmaps in the standard Xlib planar bitmap
  1167. format.  On a time scale of 60 frames per second, it is actually relatively
  1168. slow.  Since a compiled bitmap is relocatable you may just want to have it
  1169. saved to disk, and not include the source bitmap in your program at all.
  1170.     The source bitmap format is an array of bytes, a little like this:
  1171.  
  1172. char eye[] ={4, 7,  /* four byte columns across, seven rows tall */
  1173.            0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0,
  1174.            0, 0, 9, 9, 1, 1, 1, 4, 4, 9, 9, 0, 0, 0, 0, 0,
  1175.            0, 9, 9, 1, 2, 0, 0, 4, 4, 1, 9, 9, 0, 0, 0, 0,
  1176.            9, 9, 9, 1, 0, 0, 0, 0, 1, 1, 9, 9, 9, 0, 0, 0,
  1177.            0, 9, 9, 1, 2, 0, 0, 2, 1, 1, 9, 9, 0, 0, 0, 0,
  1178.            0, 0, 9, 9, 1, 1, 1, 1, 1, 9, 9, 0, 0, 0, 0, 0,
  1179.            0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0};
  1180.  
  1181.     This is actually a linear bitmap, which is the wrong format for
  1182. compilation, but is easier on human eyes.  Use the module XBMTOOLS to
  1183. convert linear bitmaps into planar bitmaps, and vice-versa.
  1184.     To compile this image for a mode 360 pixels (90 byte columns) across:
  1185.  
  1186. char planar_eye[4*7 + 2];
  1187. char far * EyeSize;
  1188.  
  1189. (void) x_bm_to_pbm((char far *) eye, (char far *) planar_eye);
  1190. EyeSize = x_sizeof_cbitmap((far char *) planar_eye);
  1191. CompiledEye = farmalloc(EyeSize);
  1192. (void) x_compile_bitmap(90, (far char *) planar_eye, CompiledEye);
  1193.  
  1194.     Notice that both buffers must exist beforehand.  Since x_compile_bitmap
  1195. returns the size of the compiled code, in bytes, you can reallocate the
  1196. bitmap immediately to the right size if using x_sizeof_xbitmap seems
  1197. inconvenient (reallocation may even be faster, though using the function is
  1198. cleaner).  The pointers are 32-bit because compiled bitmaps take so much
  1199. space: they are at one end of the speed-versus-memory spectrum.  A good
  1200. rule of thumb is to allocate (3.5 x buffer-height x buffer-width) + 25
  1201. bytes (rounding up ;-), then pare your bitmap down when you find out how
  1202. much space you've actually used.
  1203.     Since the compiled bitmap has to fit within one segment of memory, it
  1204. cannot contain more than about 19,000 pixels.  This will not be a
  1205. limitation for most sane programmers.  If you are not a sane programmer try
  1206. splitting your huge, unwieldy image up into smaller parts -- you can use
  1207. the same gigantic bitmap if you divide it into horizontal slices for
  1208. compilation.  For that matter, dividing the source up that way will let
  1209. you use a source bitmap large than 64K, which is an even sicker idea...
  1210.     Back to business.  A bitmap is compiled for only one width of screen.
  1211. If you are using a logical screen larger than your physical screen, call
  1212. the bitmap compiler with the logical width -- the important thing is the
  1213. number of bytes per line.  Notice that you do not have to be in a graphics
  1214. mode to use this routine.  This allows you to develop and compile bitmaps
  1215. separately, with whatever utility programs you might cook up.
  1216.  
  1217.     The final function is x_put_cbitmap.  To plot our eye at (99,4), on
  1218. the page which starts at location 0:
  1219. x_put_cbitmap(99, 4, 0, CompiledEye);
  1220.     This function depends on the global variable ScrnLogicalByteWidth from
  1221. the module XMAIN, which should be the same number as the column parameter
  1222. you used to compile your bitmap.
  1223.     The XCBITMAP module supports memory-to-VGA blits only.  Xlib also
  1224. includes non-masking routines which can quickly save and restore the
  1225. background screen behind your bitmap, using fast string operations.
  1226.  
  1227.    This module is part of the Xlib package, and is in the public domain.
  1228. If you write something which uses it, though, please send me a copy as a
  1229. courtesy -- if for no other reason so I can tilt my chair back and reflect
  1230. that it may have been worth the trouble after all.
  1231.  
  1232. The included program DEMO2.C demonstrates the performance difference
  1233. between planar bitmap masked blits and compiled bitmap blits.
  1234.  
  1235. --------------------------------------------------------------------------
  1236. MODULE XVBITMAP
  1237. --------------------------------------------------------------------------
  1238.  
  1239. The XVBITMAP module implements yet another type of bitmap to complement
  1240. planar and compiled bitmaps, VRAM based bitmaps. If a 4 cylinder car is
  1241. analagous to planar bitmaps, that is thrifty on memory consumption but low
  1242. performance and and a V8 is analagous to Compiled bitmaps, memory guzzlers
  1243. that really fly, then VRAM based bitmaps are the 6 cylinder modest performers
  1244. with acceptable memory consumption.
  1245.  
  1246. To summarise their selling points, VBM's are moderately fast with fair memory
  1247. consumption, and unlike compiled bitmaps, can be clipped. The disadvantages
  1248. are that they are limited by the amount of free video ram and have a complex
  1249. structure.
  1250.  
  1251. The VRAM bitmap format is rather complex consisting of components stored in
  1252. video ram and components in system ram working together. This complexity
  1253. necessitates the existence of a creation function "x_make_vbm" which takes
  1254. an input linear bitmap and generates the equivalent VBM (VRAM Bit Map).
  1255.  
  1256. VBM structure:
  1257.  
  1258.       WORD  0   Size          Total size of this VBM structure in bytes
  1259.       WORD  1   ImageWidth    Width in bytes of the image (for all alignments)
  1260.       WORD  2   ImageHeight   Height in scan lines of the image
  1261.  
  1262.       WORD  3 Alignment 0  ImagePtr   Offset in VidRAM of this aligned image
  1263.    +--WORD  4              MaskPtr    Offset (within this structure's DS) of
  1264.    |   .                   alignment masks
  1265.    |   .
  1266.    |   .
  1267.    |  WORD  9 Alignment 3  ImagePtr   Offset in VidRAM of this aligned image
  1268.   +|--WORD 10              MaskPtr    Offset (within this structure's DS) of
  1269.   ||                              alignment masks
  1270.   ||
  1271.   |+->BYTE 21 (WORD 11)                -------+-- Image masks for alignment 0
  1272.   |   .                                       |
  1273.   |   .                                       |
  1274.   |   BYTE  21 + ImageWidth*ImageHeight  -----+
  1275.   |
  1276.   |   .
  1277.   |   . (similaly for alignments 1 - 2 )
  1278.   |   .
  1279.   |
  1280.   +-->BYTE  21 + 3*ImageWidth*ImageHeight + 1-+-- Image masks for alignment 3
  1281.       .                                       |
  1282.       .                                       |
  1283.       BYTE  21 + 4*(ImageWidth*ImageHeight) --+
  1284.  
  1285.       .
  1286.       .
  1287.       << Similarly for alignments 2 and 3 >>
  1288.       .
  1289.       .
  1290.       BYTE 21 + 4*(ImageWidth*ImageHeight)
  1291.   -------------
  1292.  
  1293.   (And dont forget the corresponding data in video ram)
  1294.  
  1295. You can see for yourself the complexity of this bitmap format. The image
  1296. is stored in video ram in its 4 different alignments with pointers to these
  1297. alignments in the VBM. Similarly there are 4 alignments of the corresponding
  1298. masks within the VBM itself (towards the end). The mask bytes contain the
  1299. plane settings for the corresponding video bytes so that one memory move can
  1300. move up to 4 pixels at a time (depending on the mask settings) using the
  1301. VGA's latches, theoretically giving you a 4x speed improvement over
  1302. conventional blits like the ones implemented in "XPBITMAP". In actual fact
  1303. its anywhere between 2 and 3 due to incurred overheads.
  1304.  
  1305. These bitmaps are more difficult to store in files than PBM'S and CBM's but
  1306. still posible with a bit of work, so do not dismiss these as too difficult
  1307. to use. Consider all the bitmap formats carefully before deciding on which
  1308. to use. There may even be situations that a careful application of all three
  1309. types would be most effective ie. compiled bitmaps for Background tiles and
  1310. the main game character (which never need clipping), VRAM based bitmaps for
  1311. the most frequently occuring (oponent, alien etc) characters which get
  1312. clipped as they come into and leave your current location and planar bitmaps
  1313. for smaller or less frequently encountered characters.
  1314.  
  1315. ASM SOURCES
  1316.  
  1317.     xvbitmap.asm xvbitmap.inc xlib.inc model.inc
  1318.     xmakevbm.c  - Additional C module implementing creation function
  1319.  
  1320.   C HEADER FILE
  1321.  
  1322.     xvbitmap.h
  1323.  
  1324.   EXPORTED FUNCTIONS
  1325.  
  1326.   x_make_vbm
  1327.   ----------
  1328.  
  1329.   C Prototype: extern char far * x_make_vbm(char far *lbm, WORD *VramStart);
  1330.  
  1331.   Create the VBM from the given linear bitmap and place the image alignments
  1332.   in video ram starting at the offset in the variable pointed to by
  1333.   "VramStart". "VramStart" is then updated to point to the next free VRAM byte
  1334.   (just after the last byte of the image alignments). Usually you will point
  1335.   "VramStart" to "NonVisual_Offs".
  1336.  
  1337.    lbm         Pointer to the input linear bitmap
  1338.    VramStart   Pointer to variable containing Offset of first free VRAM byte
  1339.  
  1340.    x_put_masked_vbm
  1341.    ----------------
  1342.  
  1343.    C Prototype: extern void x_put_masked_vbm(int X, int Y, WORD ScrnOffs,
  1344.           BYTE far * VBitmap);
  1345.  
  1346.    Draw a VRAM based bitmap at (X,Y) relative to the screen with starting
  1347.    offset "ScrnOffs".
  1348.  
  1349.    x_put_masked_vbm_clipx
  1350.    ----------------------
  1351.    x_put_masked_vbm_clipy
  1352.    ----------------------
  1353.    x_put_masked_vbm_clipxy
  1354.    -----------------------
  1355.  
  1356.      Clipping versions of "x_put_masked_vbm".
  1357.  
  1358.    See XPBMCLIP for more details on the type of clipping used as it is
  1359.    identical to XVBITMAP.
  1360.  
  1361. --------------------------------------------------------------------------
  1362. MODULE  XMOUSE
  1363. --------------------------------------------------------------------------
  1364. The XMOUSE module implements very basic mouse handling functions. The way
  1365. in which it operates is by installing an event handler function during
  1366. initialization which subsequently intercepts and processes mouse events and
  1367. automatically updates status variables such as mouse position and button
  1368. pressed status. It does not support the full functionality of:
  1369.  
  1370.   SPLIT SCREENS
  1371.   SCROLLED WINDOWS
  1372.   VIRTUAL WINDOWS
  1373.  
  1374. This was done to primarily prevent unecessary impedences to performance,
  1375. since the mouse handler function has the potential to degrade performance.
  1376. It also saves me alot of coding which I was too lazy to do.
  1377.  
  1378. Programs communicate with the mouse driver as with other devices, through
  1379. an interrupt vector namely 33h. On generating an interrupt, the mouse driver
  1380. expects a function number in AX and possibly other parameters in other
  1381. registers and returns information via the registers. A brief description
  1382. of the mouse functions follows:
  1383.  
  1384.           --------------------------------------
  1385.  
  1386.           MS Mouse Driver Functions
  1387.  
  1388.           Mouse Initialization                 0
  1389.           Show Cursor                          1
  1390.           Hide Cursor                          2
  1391.           Get Mouse Position & Button Status   3
  1392.           Set Mouse Cursor Position            4
  1393.           Get Button Press Information         5
  1394.           Get Button Release Information       6
  1395.           Set Min/Max Horizontal Position      7
  1396.           Set Min/Max Vertical Position        8
  1397.           Define Graphics Cursor Block         9
  1398.           Define Text Cursor                  10
  1399.           Read Mouse Motion Counters          11
  1400.           Define Event Handler                12
  1401.           Light Pen Emulation Mode ON         13
  1402.           Light Pen Emulation Mode OFF        14
  1403.           Set Mouse Mickey/Pixel Ratio        15
  1404.           Conditional Hide Cursor             16
  1405.           Set Double-Speed Threshold          19
  1406.           --------------------------------------
  1407.  
  1408. In practice only afew of these functions are used and even fewer when the
  1409. mouse status is monitored by an event handler function such as is used in
  1410. this module.
  1411.  
  1412. The most important thing to note when using the mouse module is that the
  1413. mouse event handler must be removed before exiting the program. It is a good
  1414. idea to have an exit function (see the C "atexit" function) and include the
  1415. line "x_mouse_remove();" along with any other pre-exit cleanup code.
  1416.  
  1417.  
  1418.   ASM SOURCES
  1419.  
  1420.     xmouse.asm xlib.inc model.inc
  1421.  
  1422.   C HEADER FILE
  1423.  
  1424.     xmouse.h
  1425.  
  1426.   EXPORTED VARIABLES
  1427.  
  1428.    MouseInstalled    - WORD - Indicates whether mouse handler installed
  1429.    MouseHidden       - WORD - Indicates whether mouse cursor is hidden
  1430.    MouseButtonStatus - WORD - Holds the mouse button status
  1431.    MouseX            - WORD - Current X position of mouse cursor
  1432.    MouseY            - WORD - Current Y position of mouse cursor
  1433.    MouseFrozen       - WORD - Disallows position updates if TRUE
  1434.    MouseColor        - BYTE - The mouse cursors colour
  1435.  
  1436.   EXPORTED FUNCTIONS
  1437.  
  1438.   x_mouse_init
  1439.   ------------
  1440.  
  1441.     C Prototype:  int x_mouse_init()
  1442.  
  1443.   Initialize the mouse driver functions and install the mouse event handler
  1444.   function. This is the first function you must call before using any of the
  1445.   mouse functions. This mouse code uses the fastest possible techniques to
  1446.   save and restore mouse backgrounds and to draw the mouse cursor.
  1447.  
  1448.   WARNING: This function uses and updates "NonVisual_Offset" to allocate
  1449.        video ram for the saved mouse background.
  1450.  
  1451.   LIMITATIONS: No clipping is supported horizontally for the mouse cursor
  1452.            No validity checking is performed for NonVisual_Offs
  1453.  
  1454.   **WARNING** You must Hide or at least Freeze the mouse cursor while drawing
  1455.           using any of the other XLIB modules since the mouse handler may
  1456.           modify vga register settings at any time. VGA register settings
  1457.           are not preserved which will result in unpredictable drawing
  1458.           behavior. If you know the drawing will occur away from the
  1459.           mouse cursor set MouseFrozen to TRUE (1), do your drawing
  1460.           then set it to FALSE (0). Alternatively call "x_hide_mouse",
  1461.           perform your drawing and then call "x_show_mouse". Another
  1462.           alternative is to disable interrupts while drawing but usually
  1463.           drawing takes up alot of time and having interrupts disabled
  1464.           for too long is not a good idea.
  1465.  
  1466.   x_define_mouse_cursor
  1467.   ---------------------
  1468.  
  1469.   C Prototype:
  1470.     void x_define_mouse_cursor(char far *MouseDef, unsigned char MouseColor)
  1471.  
  1472.     MouseDef - a pointer to 14 characters containing a bitmask for all the
  1473.            cursor's rows.
  1474.     MouseColor - The colour to use when drawing the mouse cursor.
  1475.  
  1476.   Define a mouse cursor shape for use in subsequent cursor redraws. XMouse
  1477.   has a hardwired mouse cursor size of 8 pixels across by 14 pixels down.
  1478.  
  1479.   WARNING: This function assumes MouseDef points to 14 bytes.
  1480.  
  1481.   Note: Bit order is in reverse. ie bit 7 represents pixel 0 ..
  1482.     bit 0 represents pixel 7 in each "MouseDef" byte.
  1483.  
  1484.   x_show_mouse
  1485.   ------------
  1486.  
  1487.   C Prototype:  void x_show_mouse()
  1488.  
  1489.   Makes the cursor visible if it was previously hidden.
  1490.   See Also: "x_hide_mouse".
  1491.  
  1492.   x_hide_mouse
  1493.   ------------
  1494.  
  1495.   C Prototype:  void x_hide_mouse()
  1496.  
  1497.   Makes the cursor hidden if it was previously visible.
  1498.   See Also: "x_show_mouse".
  1499.  
  1500.   x_remove_mouse
  1501.   --------------
  1502.  
  1503.   C Prototype:  void x_remove_mouse()
  1504.  
  1505.   Stop mouse event handling and remove the mouse handler.
  1506.  
  1507.   NOTE: This function MUST be called before quitting the program if
  1508.        a mouse handler has been installed
  1509.  
  1510.   x_position_mouse
  1511.   ----------------
  1512.  
  1513.   C Prototype  void x_position_mouse(int x, int y)
  1514.  
  1515.   Positions the mouse cursor at the specified location
  1516.  
  1517.   x_update_mouse
  1518.   --------------
  1519.  
  1520.   C Prototype:  void x_update_mouse()
  1521.  
  1522.   Forces the mouse position to be updated and cursor to be redrawn.
  1523.   Note: this function is useful when you have set "MouseFrozen" to true.
  1524.   Allows the cursor position to be updated manually rather than
  1525.   automatically by the installed handler.
  1526.  
  1527.  
  1528. --------------------------------------------------------------------------
  1529. MODULE XBMTOOLS
  1530. --------------------------------------------------------------------------
  1531.  
  1532.   This module implements a set of functions to convert between planar
  1533.   bitmaps and linear bitmaps.
  1534.  
  1535.   PLANAR BITMAPS
  1536.  
  1537.   Planar bitmaps as used by these functions have the following structure:
  1538.  
  1539.   BYTE 0                 The bitmap width in bytes (4 pixel groups) range 1..255
  1540.   BYTE 1                 The bitmap height in rows range 1..255
  1541.   BYTE 2..n1             The plane 0 pixels width*height bytes
  1542.   BYTE n1..n2            The plane 1 pixels width*height bytes
  1543.   BYTE n2..n3            The plane 2 pixels width*height bytes
  1544.   BYTE n3..n4            The plane 3 pixels width*height bytes
  1545.  
  1546.   as used by x_put_pbm, x_get_pbm, x_put_masked_pbm.
  1547.  
  1548.   LINEAR BITMAPS
  1549.  
  1550.   Linear bitmaps have the following structure:
  1551.  
  1552.   BYTE 0                 The bitmap width in pixels  range 1..255
  1553.   BYTE 1                 The bitmap height in rows   range 1..255
  1554.   BYTE 2..n              The width*height bytes of the bitmap
  1555.  
  1556.   ASM SOURCES
  1557.  
  1558.     xbmtools.asm xpbmtools.inc model.inc
  1559.  
  1560.   C HEADER FILE
  1561.  
  1562.     xbmtools.h
  1563.  
  1564.   MACROS
  1565.  
  1566.     BM_WIDTH_ERROR
  1567.  
  1568.     LBMHeight(lbitmap)         - Height of linear bitmap "lbitmap"
  1569.     LBMWidth(lbitmap)          - Width of linear bitmap  "lbitmap"
  1570.     PBMHeight(pbitmap)         - Height of planar bitmap "pbitmap"
  1571.     PBMWidth(pbitmap)          - Width of planar bitmap "pbitmap"
  1572.  
  1573.     LBMPutPix(x,y,lbitmap,color)  - set pixel (x,y) colour in linear bitmap
  1574.     LBMGetPix(x,y,lbitmap)        - colour of pixel (x,y) in linear bitmap
  1575.  
  1576.   EXPORT FUNCTIONS
  1577.  
  1578.   x_pbm_to_bm
  1579.   ------------
  1580.   C Prototype:  extern int x_pbm_to_bm(char far * source_pbm,
  1581.                        char far * dest_bm);
  1582.  
  1583.   This function converts a bitmap in the planar format to the linear format
  1584.   as used by x_compile_bitmap.
  1585.  
  1586.   WARNING: the source and destination bitmaps must be pre - allocated
  1587.  
  1588.   NOTE: This function can only convert planar bitmaps that are suitable.
  1589.     If the source planar bitmap's width (per plane) is >= 256/4
  1590.     it cannot be converted. In this situation an error code
  1591.     BM_WIDTH_ERROR. On successful conversion 0 is returned.
  1592.  
  1593.   x_bm_to_pbm
  1594.   ------------
  1595.   C Prototype:  extern int x_bm_to_pbm(char far * source_pbm,
  1596.                        char far * dest_bm);
  1597.  
  1598.   This function converts a bitmap in the linear format as used by
  1599.   x_compile_bitmap to the planar formap.
  1600.  
  1601.   WARNING: the source and destination bitmaps must be pre - allocated
  1602.  
  1603.   NOTE: This function can only convert linear bitmaps that are suitable.
  1604.     If the source linear bitmap's width is not a multiple of 4
  1605.     it cannot be converted. In this situation an error code
  1606.     BM_WIDTH_ERROR. On successful conversion 0 is returned.
  1607.  
  1608.